



02/18/86 Initial release. 

05/08/86 Many parameter changes to accommodate menu speedups. Menu record changes and an 
alternative method of defining menus, see MENU STRINGS. Additional Mac type calls 
to help portability. Many unnecessary features that slowed things down have gone 
away. New calls Checkltem, SetltemMark, GetltemMark, Enableltem, 
Disablement, NewMenu, DisposeMenu, SetMenuID, SetltemlD, SetSysBar, 
GetSysBar, and InitPalette. 

06/18/86 Fall Down menus removed. InitMenus, BootMmgr, MmgrReset, MmgrVersion 
names changed. Additional parameter, user ID, passed to MenuStartup (formerly 
InitMenus). Direct access to menu record no longer supported. Custom menus being 
rethought, and not currently complete. GetMenuPtr and GetltemPtr removed. 
XnsertMenu and Insertltem are being redesigned, and are not complete. Now using 
standard error return code, although it is always *No error’. 

07/15/86 Changed the term Menu String to menu/item line list NewMenu now allocates only 
one menu at a time. Special characters in menu/item lines changes; X is now color 
replace highlighting, ID numbers must be included. InsertMenu, Insertltem, 
DeleteMenu, Deleteltem are complete. Custom menus are defined. 

07/16/86 Replacements for pages 8 and 9,1 wasn't using proper ID numbers in my examples. 

(" 08/13/86 Removed standard color menus. One character has been added to the front of menu and 

1 item lines. Added GetMHandle and GetMenuMgrPort calls. Changed inputs to 

, SetMenuFlag. Menu/Item strings may terminate with a zero in addition to a return. 

Change to menu records. 
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This ERS describes the Menu Manager, the pat of the Cortland Toolbox that allows you to create 
sets of menus, and allows the user to choose from the commands in those menus. 

You should already be familiar with die Cortland Event Manager. 


The Menu Manager supports the use of menus which can be part of the Cortland user interface. 
Menus allow users to examine all choices available to them at any time without being forced to 
choose one of them, and without having to remember command words or special keys. The 
Cortland user simply positions the cursor in the menu bar and presses the mouse button over a 
menu tide. The application then calls the Menu Manager, which highlights the selected tide and 
"pulls down" the menu below it As long as the mouse button is held down, the menu is 
displayed. Dragging through the menu causes each of the menu items (commands) in it to be 
highlighted in turn. If the mouse button is released over an item, that item is "chosen". The item 
blinks briefly to confirm the choice, and the menu disappears. 

When the user chooses an item, the Menu Manager tells the application which item was chosen, 
and the application performs a corresponding action. When the application completes the action, it 
removes the highlighting from the menu tide, indicating to the user that the operation is complete. 

If the user moves the cursor out of the menu with the mouse button held down, the menu remains 
visible, though no menu items are highlighted. If the mouse button is released outside the menu, 
no choice is made: The menu just disappears and the application takes no action. The user can 
always look at a menu without causing any changes in the document or on the screen. 
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A menu bar is an ou tlin ed rectangle that holds die titles of all the menus associated with the bar. A 
menu may be enabled or temporarily disabled. A disabled menu can still be pulled down, but its 
title and all the items in it are dimme d and not selectable. 


Keep in mind that if your program is likely to be translated into other languages, the menu titles 
may take up more space. If you're having trouble fitting your menus into the menu bar, you 
should review your menu organization ami menu titles. 


Th& System.Menu.Bar. 

There can be one special type of menu bar which is called the System Menu Bar. There can only be 
one system menu bar on the screen at one time. The system menu bar always appears at the top of 
die Cortland screen; nothing but the cursor ever appears in front of it. In applications that support 
desk accessories, the first menu should be the desk accessory menu (the menu whose tide is a 
colored apple symbol). The desk accessory menu contains the names of all available desk 
accessories. When the user chooses a desk accessory from the menu, the tide of a menu belonging 
to the desk accessory may appear in the menu bar, for as long as the accessory is active, or the 
entire menu bar may be replaced by menus belonging to the desk accessory. 

Color number 1 is reserved for drawing the Apple logo as the tide for the desk accessory menu. 
Therefore, color number 1 should not be used as the normal, hilite, or outline color. The color can 
be used for menus, items, nonsystem menu bars, and the rest of the screen. 











Window Menu Bars 


In addition to the System Menu Bar your application can have various window menu bars. These 
can appear anywhere in windows. Window menu bars are provided to give you more flexibility 
and to address the limi ted resolution in 320 mode. Window menu bars should be used moderately, 
ifatalL Window menu bars perform in the same manner as the System Menu Bar. 
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A standard menu consists of a n umb er of menu items listed vertically inside a shadowed rectangle. 
A menu item may be the text of a co mman d or just a line dividing groups of choices (see Figure 2). 
Menus always appear in front of everything else, except the cursor. The menu in figure 2 is a 
menu with 6 items including ore dividing line. 


Figure 2. A Standard Menu. 
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Each item can have a few visual variations from the standard appearance: 

- A mark (any charcter) may appear on the left side of the item, to denote the status of the item 
or of the mode it controls. See SetltemMark, GetltemMark, and Checkltem. 

- A apple symbol on the right side of the item, to show that the item may be invoked from the 
keyboard (that is, it has a keyboard equivalent), followed by a character. Pressing indicated 
character while holding down the Command key invokes the item just as if it had been 
chosen from the menu. See MenuKey. 

- Each item’s text may have its own text style. See SetltemStyle and GetltemStyle. 

• A dimmed appearance, to indicate that the item is disabled, and can’t be chosen (dividing 
lines should always be disabled). See Disableltem and Enableltem. 

- Any menu may be drawn directly by the application and might contain anything (see 
DEFINING YOUR OWN MENUS ). 


If the standard menu doesn't suit your needs—for example, if you want more graphics, or perhaps 
a nonlinear text arrangement—you can define a custom menu that, although visibly different to the 
user, responds to your application’s Menu Manager calls just like a standard menu (see DEFINING 
YOUR OWN MENUS). 
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Your propam can set up a keyboard equivalent for any of its menu commands so the command can 
be invoked from the keyboard with the Command key (apple key). You can assign one or two 
keyboard equivalents per item. One equivalent is the primary, and is displayed to the right of the 
item. The other equivalent is the alternate and is not displayed. The alternate equivalent should be 
the lower case equal to die primary equivalent (which should be upper case). See MenuKey for a 
discussion on how items are searched. 

Note: For consistency between applications, you should specify an upper case letter as the 
promary keyboard equivalent 


To use the Menu Manager, you must have previously initialized QuickDraw. For user interaction 
you must use the Event Manager. If you are going to be using the Window Manager, it must be 
initialized before die Menu Manager. 

The first Menu Manager routine to call is the initialization procedure, MenuStartup. Among other 
•tilings, MenuStartup will create an empty system menu bar and draw it on the screen. 

Your program then must define menus and items by providing a list of menu and item lines to 
NewMenu for each menu (see MENU LINES AND ITEM LINES) and InsertMenu to add them 
to the system menu bar. FixMenuBar may be of use in setting default sizes. 

After created, DrawMenuBar will draw the titles of the added menus. 

The following section only applies if you are using TaskMaster for standard user interaction. If 
you are not using TaskMaster, you will have to perform the following actions: 

To handle user input your application (if not using TaskMaster) calls MenuSelect or 
MenuKey with a pointer to an extended event record (see MenuSelect). From the extended 
event record, MenuSelect and MenuKey will extract information, like event position and 
' key states to determine user interaction with the current menu bar. 

MenuSelect should be called with the system menu bar when the Window Manager's 
FindWindow function returns an in System Menu Bar value after your application receives a 
mouse-down event If using multiple menus you must switch the current menu, by calling 
SetMenuBar, before calling MenuSelect. MenuSelect will return immediately if the 
starting position (event position) is not inside the menu bar. If the starting position is in the 
current menu bar, MenuSelect will retain control, and pull down appropriate menus 
—tracking the mouse, highlighting menu items, and pulling down other menus-—until the user 
releases the mouse button. 

When your application receives a key-down event with the Co mma nd key held down, it should 
call the MenuKey function, supplying it with a pointer to an extended event record which 
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contains the character that was typed and key states. Applications should respond the same 
way to auto-key events as to key-down events. MenuKey will check the event record, and 
only respond when die Command key was held down in addition to a key being entered. 


MenuSelect and MenuKey (or TaskMaster) win return a result in the TaskData field of the 
extended event record. The values returned will be: 

- Zero in the low-order WORD if there was no selection. In this case there is no further action 
required and your application should continue to poll the use. 

- If the low-order WORD is nonzero, it is the item ID of a selected item. The high-order is 
athe menu ID of the menu die selected item is in. When a selection is made, the Menu 
Manager wall leave the title of menu highlighted. Your application should then envoke an 
action which is specific to the selected item. Only after the action is completely finished 
(after all dialogs, alerts, or screen actions have been taken care of) should the application 
remove the highlighting from the affected menu title by calling HiliteMenu, signaling the 
completion of the action. 

Note: The Menu Manager will try to automatically save and restore the screen behind the 
menu, or tell the Window Manager to update the screen. However, if you are not using the 
Window Manager and the Menu Manager can not allocate a buffer large enough to save the 
screen behind the menu, your application will have to update the screen area after a menu has 
been pulled down. See CheckRedraw. 

If your menu bar, or items in a menu, are going to change while cm the screen you can use 
SetMenuTitle, InsertMenu, DeleteMenu, Setltem, Insertltem, and Deleteltem to 
rearrange the menus and items. 

There are several miscellaneous Menu Manager routines that may be of use to applications. 
CalcMenuSize calculates the dimensions of a menu and is called by FixMenuBar. 
CountMItems counts the number of items in a menu. FlashMenuBar inverts the menu bar, or 
just a menu title. SetltemBIink controls the number of times a menu item blinks when it’s 
chosen. 
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Menu Lines and Item Lines 


Menus may be created by passing a pointer to a list of menu and item lines to NewMenu which 
will parse them and allocate enough memory for necessary records, and initialize those records. 
The list can be edited using a word processor, thus allowing users to easily customize their own 
menus. An example of a list is: 

»Tide 1NN1 
“Item string 1NN256 
—Item string 2SN257 
—Item string 3SN258 


This is a simple list of one menu line and 3 item lines. The first character on a line denotes the start 
of a menu or an item in a menu. Each line is terminated by a return (decimal 13) or a null byte (0). 
Hie character to denote a tide is whatever the very first character is in the first line. The character to 
denote items is the first charsets on subsequent lines that is different from the title character. And 
lastly, a character different from the item character, and after the title, denotes the end of the list In 
the example, the V character is the tide charcter, is the item character, andis the terminating 
character. However, any characters may be used, as long as the tide and item characters are 
different, and the termination character is different from the item character. So, the title and 
termination character may be the same. 

The second character on each line (other than the termination line) is a place holder for the length of 
the string. NewMenu will replace the second character with the string's length. Therefore, after a 
NewMenu call the string data will have been altered. 

Note: The menu/item string must stay in their original memory. NewMenu sets 
pointers in the menu record to the address of the strings. 


In the example you'll notice a backslash, \', followed by a and a number. The backslash 
denotes the end of a title’s text and the beginning of special characters. The 'N’is a special 
character that precedes an ID number. A decimal, unsigned, ASCII ID number immediately 
follows. Every menu title and item must have an ID number, even dividing lines. The ID number 
for each menu title should be different from every other menu on a menu bar. The ID of an item 
should be different from every other item on a menu bar. Items that are dividing lines, and always 
disabled, can have the same ID number. 
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Special characters arc: 


\ Beginning of special characters. 

* Followed by a primary, then an alternate character to be used as a 
keyboard equivalents. Use a space for no alternate character. 

B Bold the text 

C Followed by a character to be used to mark the item. 

D To dim (disable). 

H Hexidecmal, nonASCE, ID number follows, low byte/high byte. 

I Italize the text 

N Decimal ASCII ID number follows, any length, between 1 and 65535. 
U Underscore the text 

Y Places a dividing line under the item without using a separate item. 

X Use color replace, and not XOR, highlighting. 

All the special characters pertain to items. Special characters *, B, C, I, U, and V do not pertain to 
menu titles. 


An exainple of a menu and item lines using mulitple special characters and different tide, item, and 
terminating characters: 


$Tide 1NN1 

Item string l\N256*Xx 
Item string 2SBO/UN257 
Item string 3MN258 
$ 


Tide character is '$', ID - 1, can be same as an item's. 

Item character is a space, ID * 256, key eqivalents X and x. 

Item character is a space, bold, checked, underscored, ID - 257. 
Item character is a space, text will appear italized, ID = 258. 
Terminating character, can be the same as the tide character. 


Some more special stuff. Using just the @ symbol in a tide will give you the Apple logo. An 
example of an Apple logo menu title: 

$@\N1X Apple logo tide, ID = 1, color replace highlighting. 

Note: The X special character (color replace highlighting) should always 
be used with the Apple logo. 

Note: To get the Apple logo the @ must follow the character denoting a 
menu tide, and then be followed by a special character begin mark 
or an end of line mark (return). Do not place a space before or after 
the @, like you should for other menu tides. 

There is no way to include a V in a tide's string. It will always be seen as the beginning of special 
characters. 

A single dash,for an item's text will denote a dividing line. Special characters apply to 
dividing lines. Dividing lines should always be marked as dimm ed, 'D'. 
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ID numbers are not assigned automatically, it must be assigned in the menu/item line list Item ID 
n um bers are allocated accordingly: 


$0000 

$0001 - $00FF 
$0100 - $FFFE 
SFFFF 


0 

1-255 

256-65534 

65535 


Imuamal use, generally means front, or first item in menu. 
Reserved for desk accessory items. 

Reserved for application use. 

Internal use, generally means end, or last item in menu. 


Menu ID numbers are allocated aecrodingly: 

$0000 0 Internal use, generally means front, or first menu in bar. 

$0001-$FFFE 1-65534 Reserved for application use. 

SFFFF 65535 Internal use, generally means end, or last menu in bar. 


What ID numbers to use? Here are two suggestions for schemes in ID number assignment The 
first is to number menus from 1 to n, and items from 256 to 256+n. The item ID can then be used 
to index into a table of selection handling routines when a selection is made. The other scheme is to 
use the lower WORD of the handling routine's address as the ID. Different items still must have 
different ID numbers, so NOPs at the head of the routine could be used for different entry points 
and ID numbers. 

ID numbers can later be changed to anything you would like with calls to, SetItemID, 

GetItemID, SetMenuID, and GetMenuID. 
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Menu Records 

The Menu Manager keeps all the information it requires for its operations on a particular menu bar 
in a menu bar record. The record contains the menu's position, color, menu lists, item lists, and 
other flags the Menu Manage 1 needs to manage menus. The menu bar record is the same as a 
control record, 


NextCtrl 

LONG 

CuiOwner 

LONG 

CtrlRect 

RECT 

CtrlFlag 

WORD' 

CttiValue 

WORD 

CtrlProc 

LONG 

CttiData 

LONG 

CttlRefCon 

LONG 

CtrlColor 

LONG 

MenuList 

LONGO 


Handle of next control. 

Window menu belongs to, zero for system menu bars. 
Coordinates of menu bar. 

Defined below. 

Not used, should be zoo. 

SOAOOOOOO. 

TRUE if system window’s menu, FALSE if application's. 
Reserved for application's use. 

Pointer to color table, defined below. 

Array of menu handles, zero terminates list 


Menu Bar - CtrlFlag: 



15 

14 

J3 

12 

0 

_10 

9 

8 

m 



4 

0 

0 

1 

0 




Number of hilited menu. 
Starting position of titles. 

1 * system window menu bar. 
1 * invisible. 


* Invisible flag is not yet implemented. 
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Menu Bar Color Table: 


Color 0 - unhighlighted color of text and background: 



Color 1 - highlighted color of text and background: 



Color 2 - color of outline: 











The MenuList is an array of menu handles in the menu bar. Menus records are only partially 
defined. Only the first half of the record is definded. 


Menu© 

WORD 

Menu's © number. 

MenuWidth 

WORD 

Width of menu. 

MenuHeight 

WORD 

Height of menu. 

MenuProc 

LONG 

Pointer to menu definition procedure, zoo for standard menu. 

MenuFlag 

BYTE 

Defined below. 

MenuRes 

BYTE 

Reserved. 

Firstltem 

BYTE 

Reserved. 

NumOfltems 

BYTE 

Reserved. 

TitleWidth 

WORD 

Width of tide. 

TideName 

LONG 

Pointer to tide text, first byte equals length. 


(the rest of record is not defined) 
MenuFlag 



» visible, 1 » invisible menu 

® standard, 1 ■ custom menu 
® redraw, 1 * XOR highlighting 
» normal, 1 - selected 
= enabled, 1 » disabled 


* Invisible flag is not yet implemented. 


Not defining menu records completely has good and bad sides. Access to menu information will 
be slower if calls to the Menu Manager have to be made. However, the delay would have to be 
measured in miliseconds, and the delay never seen on the screen. On the plus side, future Menu 
Managers would not be tied to an older, possibly inadequate, record structure. The chances of 
improving the ament Mam Manager, and maintaining compatibility aceross future hardware, is 
greatly improved by allowing records; to change. 

Item records not defined at all for standard menus. 
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The standard type of menu is predefined f or you. However, you may want to define your own 
type of menu—one with more graphics, or perhaps a nonlinear text arrangement QuickDraw and 
the Menu Manager make it possible for you to do this. 

To define your own type of menu, you write a menu definition procedure. The Menu Manager 
calls the menu definition procedure to perform basic operations such as drawing the menu. 

To create a custom menu record you will have to allocate a block of memory large enough for your 
menu record. Only the defined part (see MENU RECORDS) of the menu record has to follow 
Menu Manager form, tile rest of the record is up to you. Another way is to pass a menu line with 
no items to NewMemi and that resize the allocated block to your needs. Helds in die menu 
record that need to be initialized are: 

MenuID Menu's HD number. 

MenuWidth Width of menu, or you can wait for die mSize. 

MenuHeight Height of menu, or you can wait for the mSize. 

MenuProc Pointer to mam definition procedure. 

MenuFlag In addition to other flags, bit 4 must be set 

TideWidth Width of title. 

TltleName Pointer to title text, first byte equals length. Or some other data you wish. 


(not completed) 


You may choose any name you wish for the menu definition procedure. The inputs and outputs 
are: 

inputs: message:WORD Operation to perfrom. 

theMemuLONG Handle of menu. 

RcctPtr.LONG Pointer to RECT enclosing menu. 



The parameter theMenu indicates the menu that the operation will affect RectPtr is the rectangle (in 
global coordinates) in which the operation is to be performed. 
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mDrawMcnu 


He message mDrawMenu tells the menu definition procedure to draw the menu inside the RECT 
pointed to by RectPff. The current grafPort will be the Menu Manager port. The standard menu 
definition procedure figures out how to draw the menu items by looking in the menu record at the 
data that defines them. For menus of your own definition, you may set up the data defining the 
menu items any way you like. You should also check the enableFkgs field of the menu record to 
see whether the menu is disabled (or whether any of the menu items are disabled, if you’re using all 
the flags), and if so, draw it in gray. You may even print the items in a different font, as long as 
you restore the original when you finish. Retinned value is not used. 


mGififiSfi 

When the menu definition procedure receives the message mChoose, the yffitPf/xHitPt parameter is 
the mouse location (in global coordinates), and the param parameter is the item number of the last 
item that was chosen from this menu (param is initially set to 0). The procedure should determine 
whether the mouse location is in an enabled menu item, by checking whether yHitPt/xHitPt is 
inside the RECT pointed to by RectPtr, whether the menu is enabled, and whether yHitPt/xHitPt is 
in an enabled menu item: 

- If the mouse location is in an enabled menu item, unhighlight param and highlight the new 
item (unless the new item is the same as the param), and return the item number of the new 
item. 

- If the mouse location isn’t in an. enabled item, unhighlight param and rearm zero. 

Note: When the Menu Manager needs to make a chosen menu item blink, it repeatedly calls 
the menu definition procedure with the message mChoose, causing the item to be 
alternately higiilighted and unhighlighted. 


roS lza 

Finally, the message mSize tells the menu definition procedure to calculate the horizontal and 
vertical dimensions of the menu and store them in the menuWIdth and menuHeight fields of the 
menu record. Returned value is not used. 


mtaxTidfi 

When the menu definition procedure receives the message mDrawTitle when the title of the menu 
must be drawn. The param parameter is FALSE to draw the title as unhighlighted, and TRUE to 
draw as highlighted. The RECT pointed to by RectPtr encloses die title area. Return FALSE to 
have the Menu Manager draw the tide, if the title is a text string pointed to by TitleName. Return 
TRUE if you complete the operation. 


. i 
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The nxDrawIteffl co mman d is a request to draw an item in its highlighted or unhighlighted state. If 
param is positive it is the item number and should be draw draw as unhighlighted. If param is 
negative it is the negated form of the item number and should be drawn as highlighted. This 
command is given when the user makes a selection and is used to blink, the selection. 


Param equals the item's number and the definition procedure is asked to return the item's ID 
number. The item number is die value returned by mChoose. 
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There are two standard ways to partition groups of items from one another. The first is a dividing 
line, selected by an item title which is a single dash. It uses the space of an entire item and a whole 
item record. The second way is a underline, set either in the menu line, or SetltemFlag. This 
will draw a solid line on the bottom most line of the item. The underline doesn't use any more 
space, on the screen or in memory, than the item would without it. 

The disadvantage with an underline is there isn't as much space separating items, which is the 
dividing line's function. 

The advantage of an underline is you can get more items in the menu and still have dmdh.. 0 _ 

Also, the user would have a shorter distance to go from the menu's title to the last item in the menu, 
it would save a little memory, and the menu would draw faster. 

In the example below are two menus, both showing the same information. Menu A uses dividing 
lines and has 9 items. Menu B uses underlines and has 7 items. Menu B looks alittle crowded and 
would look even worse if one of the uderlined items had descending lower case letters. 


Menu A - Dividing Lines Menu B - Underlines 








